JavaScript Temporal API: دستکاری مدرن تاریخ و زمان

شیء Date جاوا اسکریپت مدت هاست که منبع ناامیدی برای توسعه دهندگان بوده است. تغییرپذیری، عدم پشتیبانی داخلی از منطقه زمانی و API نامناسب آن منجر به کتابخانه ها و راه حل های بی شماری شده است. خوشبختانه، Temporal API با هدف رفع این کاستی ها، یک راه حل مدرن، شهودی و آگاه از منطقه زمانی برای دستکاری تاریخ و زمان در جاوا اسکریپت ارائه می دهد.

Temporal API چیست؟

Temporal API یک شیء سراسری جدید، Temporal است که یک روش مدرن و استاندارد برای کار با تاریخ ها و زمان ها در جاوا اسکریپت فراهم می کند. این API برای جایگزینی شیء Date قدیمی طراحی شده است و بهبودهای قابل توجهی از نظر طراحی API، تغییرناپذیری، پشتیبانی از منطقه زمانی و قابلیت استفاده کلی ارائه می دهد. این API بخشی از پیشنهاد ECMAScript است و در موتورهای اصلی جاوا اسکریپت در حال پیاده سازی است.

مزایای کلیدی Temporal API:

• تغییرناپذیری: اشیاء Temporal تغییرناپذیر هستند، به این معنی که عملیات روی آنها اشیاء جدیدی را برمی گرداند به جای اینکه شیء اصلی را تغییر دهد. این به جلوگیری از عوارض جانبی غیرمنتظره کمک می کند و درک کد را آسان تر می کند.
• API واضح: این API به گونه ای طراحی شده است که شهودی تر و سازگارتر از شیء Date قدیمی باشد.
• پشتیبانی از منطقه زمانی: Temporal پشتیبانی قوی از مناطق زمانی ارائه می دهد و به شما امکان می دهد با تاریخ ها و زمان ها در مکان های مختلف در سراسر جهان کار کنید.
• پشتیبانی از تقویم: فراتر از تقویم میلادی، API اجازه می دهد تا از سیستم های تقویم دیگر نیز استفاده شود و برنامه های کاربردی جهانی را تسهیل می کند.
• مدیریت ثانیه های کبیسه: Temporal API ثانیه های کبیسه را در نظر می گیرد و محاسبات دقیق تری از زمان ارائه می دهد.

شروع کار با Temporal

در حالی که Temporal API هنوز در حال توسعه است و هنوز به طور کامل در همه مرورگرها و محیط های Node.js پشتیبانی نمی شود، می توانید از یک polyfill برای شروع آزمایش با آن استفاده کنید. می توانید polyfill را از طریق npm نصب کنید:

            npm install @js-temporal/polyfill
            

              
                Copy
              
            
          

سپس، polyfill را در کد جاوا اسکریپت خود وارد کنید:

            import { Temporal } from '@js-temporal/polyfill';
            

              
                Copy
              
            
          

پس از نصب polyfill، می توانید شروع به استفاده از شیء Temporal و کلاس های مختلف آن کنید.

کلاس های اصلی Temporal

Temporal API چندین کلاس کلیدی برای کار با تاریخ ها و زمان ها ارائه می دهد:

• Temporal.PlainDate: نشان دهنده یک تاریخ تقویمی (سال، ماه و روز) بدون هیچ گونه اطلاعات منطقه زمانی یا زمان روز است.
• Temporal.PlainTime: نشان دهنده زمان روز (ساعت، دقیقه، ثانیه و کسری از ثانیه) بدون هیچ گونه اطلاعات تاریخ یا منطقه زمانی است.
• Temporal.PlainDateTime: نشان دهنده تاریخ و زمان بدون هیچ گونه اطلاعات منطقه زمانی است.
• Temporal.ZonedDateTime: نشان دهنده تاریخ و زمان با یک منطقه زمانی خاص است.
• Temporal.Instant: نشان دهنده یک نقطه خاص در زمان است که بر حسب نانوثانیه از زمان epoch یونیکس اندازه گیری می شود (1 ژانویه 1970، ساعت 00:00:00 زمان هماهنگ جهانی (UTC)).
• Temporal.TimeZone: نشان دهنده یک منطقه زمانی است.
• Temporal.Duration: نشان دهنده یک مدت زمان است، مانند ساعت، دقیقه یا ثانیه.
• Temporal.Now: دسترسی به تاریخ و زمان فعلی را فراهم می کند.

کار با PlainDate

کلاس Temporal.PlainDate نشان دهنده یک تاریخ بدون هیچ گونه اطلاعات منطقه زمانی یا زمان روز است. برای نشان دادن تولدها، سالگردها یا سایر رویدادهای مبتنی بر تاریخ مفید است.

ایجاد یک PlainDate:

            const plainDate = Temporal.PlainDate.from({ year: 2024, month: 10, day: 26 });
console.log(plainDate.toString()); // Output: 2024-10-26
            

              
                Copy
              
            
          

همچنین می توانید یک PlainDate از یک رشته در قالب ISO 8601 ایجاد کنید:

            const plainDateFromString = Temporal.PlainDate.from('2024-12-25');
console.log(plainDateFromString.toString()); // Output: 2024-12-25
            

              
                Copy
              
            
          

دسترسی به اجزای تاریخ:

            const year = plainDate.year; // 2024
const month = plainDate.month; // 10
const day = plainDate.day;   // 26
const dayOfWeek = plainDate.dayOfWeek; // Day of the week (1-7, Monday-Sunday)
const dayOfYear = plainDate.dayOfYear; // Day of the year (1-366)
const daysInMonth = plainDate.daysInMonth; // Number of days in the month
const isLeapYear = plainDate.isLeapYear;   // Boolean indicating if the year is a leap year
            

              
                Copy
              
            
          

افزودن و کم کردن روزها:

            const nextDay = plainDate.add({ days: 1 });
console.log(nextDay.toString()); // Output: 2024-10-27

const previousWeek = plainDate.subtract({ weeks: 1 });
console.log(previousWeek.toString()); // Output: 2024-10-19
            

              
                Copy
              
            
          

مقایسه تاریخ ها:

            const anotherDate = Temporal.PlainDate.from({ year: 2024, month: 11, day: 15 });

if (plainDate.equals(anotherDate)) {
 console.log('Dates are equal');
} else if (plainDate.lessThan(anotherDate)) {
 console.log('plainDate is earlier than anotherDate');
} else {
 console.log('plainDate is later than anotherDate');
}
// Output: plainDate is earlier than anotherDate
            

              
                Copy
              
            
          

کار با PlainTime

کلاس Temporal.PlainTime نشان دهنده زمان روز بدون هیچ گونه اطلاعات تاریخ یا منطقه زمانی است. برای نشان دادن ساعات کاری، زمان جلسات یا سایر رویدادهای مبتنی بر زمان مفید است.

ایجاد یک PlainTime:

            const plainTime = Temporal.PlainTime.from({ hour: 14, minute: 30, second: 0 });
console.log(plainTime.toString()); // Output: 14:30:00
            

              
                Copy
              
            
          

همچنین می توانید یک PlainTime از یک رشته در قالب ISO 8601 ایجاد کنید:

            const plainTimeFromString = Temporal.PlainTime.from('09:00:00');
console.log(plainTimeFromString.toString()); // Output: 09:00:00
            

              
                Copy
              
            
          

دسترسی به اجزای زمان:

            const hour = plainTime.hour;   // 14
const minute = plainTime.minute; // 30
const second = plainTime.second; // 0
const millisecond = plainTime.millisecond; // 0
const microsecond = plainTime.microsecond; // 0
const nanosecond = plainTime.nanosecond;   // 0
            

              
                Copy
              
            
          

افزودن و کم کردن زمان:

            const laterTime = plainTime.add({ minutes: 15 });
console.log(laterTime.toString()); // Output: 14:45:00

const earlierTime = plainTime.subtract({ hours: 1 });
console.log(earlierTime.toString()); // Output: 13:30:00
            

              
                Copy
              
            
          

مقایسه زمان ها:

            const anotherTime = Temporal.PlainTime.from({ hour: 15, minute: 0, second: 0 });

if (plainTime.equals(anotherTime)) {
 console.log('Times are equal');
} else if (plainTime.lessThan(anotherTime)) {
 console.log('plainTime is earlier than anotherTime');
} else {
 console.log('plainTime is later than anotherTime');
}
// Output: plainTime is earlier than anotherTime
            

              
                Copy
              
            
          

کار با PlainDateTime

کلاس Temporal.PlainDateTime نشان دهنده تاریخ و زمان بدون هیچ گونه اطلاعات منطقه زمانی است. این کلاس عملکرد PlainDate و PlainTime را ترکیب می کند.

ایجاد یک PlainDateTime:

            const plainDateTime = Temporal.PlainDateTime.from({ year: 2024, month: 10, day: 26, hour: 14, minute: 30, second: 0 });
console.log(plainDateTime.toString()); // Output: 2024-10-26T14:30:00
            

              
                Copy
              
            
          

همچنین می توانید یک PlainDateTime از یک رشته در قالب ISO 8601 ایجاد کنید:

            const plainDateTimeFromString = Temporal.PlainDateTime.from('2024-12-25T09:00:00');
console.log(plainDateTimeFromString.toString()); // Output: 2024-12-25T09:00:00
            

              
                Copy
              
            
          

دسترسی به اجزای تاریخ و زمان:

            const year = plainDateTime.year;   // 2024
const month = plainDateTime.month; // 10
const day = plainDateTime.day;     // 26
const hour = plainDateTime.hour;   // 14
const minute = plainDateTime.minute; // 30
const second = plainDateTime.second; // 0
            

              
                Copy
              
            
          

افزودن و کم کردن تاریخ ها و زمان ها:

            const nextDayAndTime = plainDateTime.add({ days: 1, hours: 2 });
console.log(nextDayAndTime.toString()); // Output: 2024-10-27T16:30:00

const previousWeekAndTime = plainDateTime.subtract({ weeks: 1, minutes: 30 });
console.log(previousWeekAndTime.toString()); // Output: 2024-10-19T14:00:00
            

              
                Copy
              
            
          

تبدیل به PlainDate و PlainTime:

            const plainDateFromDateTime = plainDateTime.toPlainDate();
console.log(plainDateFromDateTime.toString()); // Output: 2024-10-26

const plainTimeFromDateTime = plainDateTime.toPlainTime();
console.log(plainTimeFromDateTime.toString()); // Output: 14:30:00
            

              
                Copy
              
            
          

کار با ZonedDateTime

کلاس Temporal.ZonedDateTime نشان دهنده تاریخ و زمان با یک منطقه زمانی خاص است. این برای برنامه هایی که نیاز به مدیریت تاریخ ها و زمان ها در مکان های مختلف در سراسر جهان دارند بسیار مهم است. برخلاف شیء Date قدیمی، Temporal پشتیبانی داخلی از منطقه زمانی را فراهم می کند.

ایجاد یک ZonedDateTime:

            const zonedDateTime = Temporal.ZonedDateTime.from({ year: 2024, month: 10, day: 26, hour: 14, minute: 30, second: 0, timeZone: 'America/Los_Angeles' });
console.log(zonedDateTime.toString()); // Output: 2024-10-26T14:30:00-07:00[America/Los_Angeles]
            

              
                Copy
              
            
          

همچنین می توانید یک ZonedDateTime از یک Instant و یک منطقه زمانی ایجاد کنید:

            const instant = Temporal.Instant.fromEpochSeconds(1666785000); // Example timestamp
const zonedDateTimeFromInstant = instant.toZonedDateTimeISO('Europe/London');
console.log(zonedDateTimeFromInstant.toString()); // Output will vary based on the actual instant but will reflect the date/time in Europe/London
            

              
                Copy
              
            
          

دسترسی به اجزای تاریخ و زمان:

            const year = zonedDateTime.year;   // 2024
const month = zonedDateTime.month; // 10
const day = zonedDateTime.day;     // 26
const hour = zonedDateTime.hour;   // 14
const minute = zonedDateTime.minute; // 30
const second = zonedDateTime.second; // 0
const timeZone = zonedDateTime.timeZone; // Temporal.TimeZone object
            

              
                Copy
              
            
          

تبدیل بین مناطق زمانی:

            const newYorkDateTime = zonedDateTime.withTimeZone('America/New_York');
console.log(newYorkDateTime.toString()); // Output: 2024-10-26T17:30:00-04:00[America/New_York]
            

              
                Copy
              
            
          

مدیریت زمان صرفه جویی در نور روز (DST):

Temporal به طور خودکار انتقال DST را مدیریت می کند. هنگام افزودن یا کم کردن زمان، DST را در نظر می گیرد و نتایج دقیقی را تضمین می کند. به عنوان مثال، جلسه ای را در نظر بگیرید که در طول انتقال DST در آلمان برنامه ریزی شده است:

            const meetingStart = Temporal.ZonedDateTime.from({ year: 2024, month: 3, day: 31, hour: 2, minute: 30, timeZone: 'Europe/Berlin' });
const meetingEnd = meetingStart.add({ hours: 1 }); // Adding 1 hour
console.log(meetingEnd.toString()); // Output: 2024-03-31T03:30:00+02:00[Europe/Berlin]. Notice the offset changes due to DST
            

              
                Copy
              
            
          

کار با Instant

کلاس Temporal.Instant نشان دهنده یک نقطه خاص در زمان است که بر حسب نانوثانیه از زمان epoch یونیکس اندازه گیری می شود. برای ذخیره و مقایسه لحظات دقیق در زمان مفید است.

ایجاد یک Instant:

            const instant = Temporal.Instant.fromEpochSeconds(1666785000); // Example Unix timestamp in seconds
console.log(instant.toString()); // Output will be an ISO string representation of that instant
            

              
                Copy
              
            
          

تبدیل به ZonedDateTime:

            const zonedDateTimeFromInstant = instant.toZonedDateTimeISO('America/Los_Angeles');
console.log(zonedDateTimeFromInstant.toString()); // Output: Date and time in America/Los_Angeles corresponding to the instant
            

              
                Copy
              
            
          

مقایسه Instant ها:

            const anotherInstant = Temporal.Instant.fromEpochSeconds(1666790000);

if (instant.equals(anotherInstant)) {
 console.log('Instants are equal');
} else if (instant.lessThan(anotherInstant)) {
 console.log('instant is earlier than anotherInstant');
} else {
 console.log('instant is later than anotherInstant');
}
// Output: instant is earlier than anotherInstant
            

              
                Copy
              
            
          

کار با Duration

کلاس Temporal.Duration نشان دهنده یک مدت زمان است، مانند ساعت، دقیقه یا ثانیه. برای محاسبه تفاوت بین دو تاریخ یا زمان مفید است.

ایجاد یک Duration:

            const duration = Temporal.Duration.from({ hours: 2, minutes: 30 });
console.log(duration.toString()); // Output: PT2H30M
            

              
                Copy
              
            
          

محاسبه تفاوت بین تاریخ ها/زمان ها:

            const startDate = Temporal.PlainDateTime.from({ year: 2024, month: 1, day: 1, hour: 0, minute: 0, second: 0 });
const endDate = Temporal.PlainDateTime.from({ year: 2024, month: 1, day: 3, hour: 12, minute: 30, second: 0 });
const difference = endDate.since(startDate);
console.log(difference.toString()); // Output: P2DT12H30M

// Accessing the components of the duration
console.log(difference.days);    // 2
console.log(difference.hours);   // 12
console.log(difference.minutes); // 30
            

              
                Copy
              
            
          

افزودن Duration به تاریخ ها/زمان ها:

            const newDate = startDate.add(duration);
console.log(newDate.toString()); // Output: 2024-01-03T02:30:00
            

              
                Copy
              
            
          

کار با تقویم ها

Temporal API از سیستم های تقویم مختلف فراتر از تقویم میلادی پشتیبانی می کند. در حالی که هنوز به طور کامل در همه polyfill ها و موتورها پیاده سازی نشده است، هدف این است که به برنامه ها اجازه دهد تاریخ ها را در تقویم های خاص فرهنگ های مختلف مدیریت کنند. به عنوان مثال، برای استفاده از تقویم ژاپنی (به طور فرضی، از آنجا که پیاده سازی هنوز در حال تحول است):

            // This is a conceptual example as calendar support is still under development
// const japaneseDate = Temporal.PlainDate.from({ year: 2024, month: 10, day: 26, calendar: 'japanese' });
// console.log(japaneseDate.toString()); // Expected: Output formatted according to the Japanese calendar

            

              
                Copy
              
            
          

توجه: پشتیبانی از تقویم یک ویژگی در حال تکامل Temporal API است و عملکرد کامل هنوز به طور جهانی در دسترس نیست.

مثال ها و موارد استفاده عملی

Temporal API طیف گسترده ای از امکانات را برای مدیریت تاریخ ها و زمان ها در جاوا اسکریپت ارائه می دهد. در اینجا چند نمونه عملی و موارد استفاده آورده شده است:

• برنامه ریزی قرار ملاقات ها: یک برنامه زمان بندی ایجاد کنید که به کاربران امکان می دهد قرار ملاقات ها را در منطقه زمانی محلی خود رزرو کنند. Temporal.ZonedDateTime تبدیل بین مناطق زمانی و مدیریت انتقال DST را آسان می کند. برای یک کلینیک در برلین که قرار ملاقات ها را به صورت جهانی برنامه ریزی می کند:

            const appointmentTimeBerlin = Temporal.ZonedDateTime.from({ year: 2024, month: 11, day: 5, hour: 10, minute: 0, timeZone: 'Europe/Berlin' });
const appointmentTimeLA = appointmentTimeBerlin.withTimeZone('America/Los_Angeles');
console.log(`Appointment Time in Berlin: ${appointmentTimeBerlin.toString()}`);
console.log(`Appointment Time in Los Angeles: ${appointmentTimeLA.toString()}`);
            

              
                Copy
              
            
          

• محاسبه سن: سن یک کاربر را بر اساس تاریخ تولد او تعیین کنید. PlainDate به شما امکان می دهد تاریخ تولد را بدون هیچ گونه اطلاعات منطقه زمانی نشان دهید.

            const birthDate = Temporal.PlainDate.from({ year: 1990, month: 5, day: 15 });
const today = Temporal.Now.plainDateISO();
const age = today.year - birthDate.year - (today.month < birthDate.month || (today.month === birthDate.month && today.day < birthDate.day) ? 1 : 0);
console.log(`Age: ${age}`);
            

              
                Copy
              
            
          

• نمایش تاریخ ها و زمان ها در قالب های مختلف: تاریخ ها و زمان ها را مطابق با منطقه کاربر قالب بندی کنید. در حالی که ویژگی های بین المللی سازی (Intl) جدا هستند، اشیاء Temporal را می توان به راحتی با استفاده از toLocaleString() یا روش های مشابه هنگام ترکیب با ویژگی های Intl API قالب بندی کرد.

            const zonedDateTimeNow = Temporal.Now.zonedDateTimeISO('en-GB');
console.log(zonedDateTimeNow.toLocaleString('en-GB'));
console.log(zonedDateTimeNow.toLocaleString('de-DE'));
            

              
                Copy
              
            
          

• پیگیری مدت زمان رویداد: مدت زمان یک رویداد را محاسبه کرده و آن را در یک قالب قابل خواندن توسط انسان نمایش دهید. Duration به شما امکان می دهد تفاوت زمانی بین دو تاریخ یا زمان را نشان دهید.

            const eventStart = Temporal.Instant.fromEpochSeconds(1700000000); // Example start timestamp
const eventEnd = Temporal.Instant.fromEpochSeconds(1700005000);   // Example end timestamp
const durationOfEvent = eventEnd.since(eventStart);
console.log(`Event duration: ${durationOfEvent.minutes} minutes`);
            

              
                Copy
              
            
          

بهترین شیوه ها برای استفاده از Temporal API

در اینجا چند بهترین شیوه برای به خاطر سپردن هنگام استفاده از Temporal API وجود دارد:

• از تغییرناپذیری استفاده کنید: تغییرناپذیری اشیاء Temporal را بپذیرید. از تغییر مستقیم اشیاء خودداری کنید. در عوض، اشیاء جدید را با استفاده از روش هایی مانند add، subtract و with ایجاد کنید.
• مناطق زمانی را با دقت مدیریت کنید: هنگام کار با تاریخ ها و زمان ها، به مناطق زمانی توجه داشته باشید. هنگام نیاز به نمایش تاریخ ها و زمان ها در یک منطقه زمانی خاص، از ZonedDateTime استفاده کنید.
• از نام های متغیر واضح استفاده کنید: از نام های متغیر توصیفی استفاده کنید که به وضوح نوع شیء Temporal مورد استفاده را نشان می دهند (به عنوان مثال، plainDate، zonedDateTime، duration).
• Polyfill ها را در نظر بگیرید: از آنجا که Temporal هنوز نسبتاً جدید است، با استفاده از یک کتابخانه polyfill در صورت نیاز، از پشتیبانی کافی اطمینان حاصل کنید.
• ورودی را اعتبارسنجی کنید: همیشه ورودی کاربر را اعتبارسنجی کنید تا اطمینان حاصل شود که تاریخ ها و زمان ها در قالب صحیح هستند.

انتقال از Date قدیمی

انتقال از شیء Date قدیمی می تواند یک فرآیند تدریجی باشد. این استراتژی ها را در نظر بگیرید:

• پذیرش افزایشی: با استفاده از Temporal در کد جدید شروع کنید و در عین حال Date را در قسمت های موجود برنامه خود حفظ کنید.
• توابع Wrapper: توابع wrapper ایجاد کنید که بین اشیاء Date و Temporal تبدیل می شوند تا قابلیت همکاری در طول انتقال را تسهیل کنند.
• آزمایش کامل: مهاجرت را به طور گسترده آزمایش کنید تا اطمینان حاصل شود که تمام محاسبات تاریخ و زمان دقیق هستند.

Temporal API در مقابل Moment.js

Moment.js یک کتابخانه محبوب برای دستکاری تاریخ و زمان در جاوا اسکریپت بود، اما اکنون یک پروژه قدیمی در نظر گرفته می شود و در حالت نگهداری است. Temporal API یک راه حل مدرن تر و استانداردتر ارائه می دهد که بسیاری از کاستی های Moment.js را برطرف می کند. Moment.js قابل تغییر است و از منطقه زمانی بومی پشتیبانی نمی کند. Temporal API غیرقابل تغییر است و از منطقه زمانی بومی پشتیبانی می کند.

نتیجه گیری

JavaScript Temporal API نشان دهنده یک پیشرفت قابل توجه نسبت به شیء Date قدیمی است. تغییرناپذیری، API واضح، پشتیبانی از منطقه زمانی و پشتیبانی از تقویم آن را به ابزاری قدرتمند برای مدیریت تاریخ ها و زمان ها در برنامه های کاربردی مدرن جاوا اسکریپت تبدیل کرده است. در حالی که پذیرش هنوز در حال رشد است، استفاده از یک polyfill به شما امکان می دهد تا امروز از مزایای آن استفاده کنید. از آنجا که API به طور گسترده تری پشتیبانی می شود، انتظار می رود که به روش استاندارد برای کار با تاریخ ها و زمان ها در جاوا اسکریپت تبدیل شود.

Temporal API را بپذیرید و راهی کارآمدتر و قابل اعتمادتر برای مدیریت تاریخ ها و زمان ها در پروژه های خود را باز کنید و اطمینان حاصل کنید که برنامه شما مناطق زمانی جهانی و محاسبات را به طور دقیق مدیریت می کند.